home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 October: Mac OS SDK / Dev.CD Oct 00 SDK1.toast / Development Kits / Cross Platform / QuickTime 4.1.2 Windows SDK / CIncludes / MacHelp.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-04-12  |  13.3 KB  |  373 lines  |  [TEXT/R*ch]
  1. /*
  2.      File:        MacHelp.h
  3.  
  4.      Contains:    Macintosh Help Package Interfaces.
  5.  
  6.      Version:    Technology:    CarbonLib 1.0
  7.                  Release:    QuickTime 4.1
  8.  
  9.      Copyright:    (c) 1998-1999 by Apple Computer, Inc., all rights reserved
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. */
  17. #ifndef __MACHELP__
  18. #define __MACHELP__
  19.  
  20. #ifndef __CONTROLS__
  21.     #include <Controls.h>
  22. #endif
  23.  
  24. #ifndef __DIALOGS__
  25.     #include <Dialogs.h>
  26. #endif
  27.  
  28. #ifndef __EVENTS__
  29.     #include <Events.h>
  30. #endif
  31.  
  32. #ifndef __MACWINDOWS__
  33.     #include <MacWindows.h>
  34. #endif
  35.  
  36. #ifndef __MENUS__
  37.     #include <Menus.h>
  38. #endif
  39.  
  40. #ifndef __MOVIES__
  41.     #include <Movies.h>
  42. #endif
  43.  
  44.  
  45.  
  46.  
  47. #if PRAGMA_ONCE
  48. #pragma once
  49. #endif
  50.  
  51. #ifdef __cplusplus
  52. extern "C" {
  53. #endif
  54.  
  55. #if PRAGMA_IMPORT
  56. #pragma import on
  57. #endif
  58.  
  59. #if PRAGMA_STRUCT_ALIGN
  60.     #pragma options align=mac68k
  61. #elif PRAGMA_STRUCT_PACKPUSH
  62.     #pragma pack(push, 2)
  63. #elif PRAGMA_STRUCT_PACK
  64.     #pragma pack(2)
  65. #endif
  66.  
  67. /*----------------------------------------------------------------------------------*/
  68. /* Help Manager constants, etc.                                                        */
  69. /*----------------------------------------------------------------------------------*/
  70. #ifndef __BALLOONS__
  71. enum {
  72.     kMacHelpVersion                = 0x0003,
  73.     hmBalloonHelpVersion        = kMacHelpVersion                /* Backwards compatibility */
  74. };
  75.  
  76. #endif  /* !defined(__BALLOONS__) */
  77.  
  78.  
  79. typedef SInt16 HMContentRequest;
  80. enum {
  81.     kHMSupplyContent            = 0,
  82.     kHMDisposeContent            = 1
  83. };
  84.  
  85.  
  86. typedef UInt32 HMContentType;
  87. enum {
  88.     kHMNoContent                = FOUR_CHAR_CODE('none'),
  89.     kHMPascalStrContent            = FOUR_CHAR_CODE('pstr'),
  90.     kHMPictResContent            = FOUR_CHAR_CODE('pict'),
  91.     kHMStringResContent            = FOUR_CHAR_CODE('str#'),
  92.     kHMTEHandleContent            = FOUR_CHAR_CODE('txth'),
  93.     kHMPictHandleContent        = FOUR_CHAR_CODE('pcth'),
  94.     kHMTextResContent            = FOUR_CHAR_CODE('text'),
  95.     kHMStrResContent            = FOUR_CHAR_CODE('str '),
  96.     kHMMovieContent                = FOUR_CHAR_CODE('moov')
  97. };
  98.  
  99.  
  100. typedef SInt16 HMTagDisplaySide;
  101. enum {
  102.     kHMDefaultSide                = 0,
  103.     kHMTopSide                    = 1,
  104.     kHMLeftSide                    = 2,
  105.     kHMBottomSide                = 3,
  106.     kHMRightSide                = 4,
  107.     kHMTopLeftCorner            = 5,
  108.     kHMTopRightCorner            = 6,
  109.     kHMLeftTopCorner            = 7,
  110.     kHMLeftBottomCorner            = 8,
  111.     kHMBottomLeftCorner            = 9,
  112.     kHMBottomRightCorner        = 10,
  113.     kHMRightTopCorner            = 11,
  114.     kHMRightBottomCorner        = 12
  115. };
  116.  
  117.  
  118. typedef SInt16 HMContentProvidedType;
  119. enum {
  120.     kHMContentProvided            = 0,
  121.     kHMContentNotProvided        = 1,
  122.     kHMContentNotProvidedDontPropagate = 2
  123. };
  124.  
  125. enum {
  126.     kHMMinimumContentIndex        = 0,
  127.     kHMMaximumContentIndex        = 1
  128. };
  129.  
  130. enum {
  131.     kHMIllegalContentForMinimumState = -1000                    /* *** Need real numbers here*/
  132. };
  133.  
  134. enum {
  135.     kHMHelpPropertyContentTag    = FOUR_CHAR_CODE('help')
  136. };
  137.  
  138. #ifndef __BALLOONS__
  139.  
  140. struct HMStringResType {
  141.     short                             hmmResID;
  142.     short                             hmmIndex;
  143. };
  144. typedef struct HMStringResType            HMStringResType;
  145. #endif  /* !defined(__BALLOONS__) */
  146.  
  147.  
  148. struct HMHelpContent {
  149.     HMContentType                     contentType;
  150.     union {
  151.         Str255                             tagString;                /* Pascal String*/
  152.         SInt16                             tagPictID;                /* 'PICT' resource ID*/
  153.         HMStringResType                 tagStringRes;            /* STR# resource ID and index*/
  154.         TEHandle                         tagTEHandle;            /* TextEdit handle*/
  155.         PicHandle                         tagPictHandle;            /* Picture handle*/
  156.         SInt16                             tagTextRes;                /* TEXT/styl resource ID*/
  157.         SInt16                             tagStrRes;                /* STR resource ID*/
  158.         Movie                             tagMovie;                /* QuickTime movie*/
  159.     }                                 u;
  160. };
  161. typedef struct HMHelpContent            HMHelpContent;
  162.  
  163. struct HMHelpContentRec {
  164.     SInt32                             version;
  165.     Rect                             absHotRect;
  166.     HMTagDisplaySide                 tagSide;
  167.     HMHelpContent                     content[2];
  168. };
  169. typedef struct HMHelpContentRec            HMHelpContentRec;
  170.  
  171. typedef HMHelpContentRec *                HMHelpContentPtr;
  172. /*------------------------------------------------------------------------------------------*/
  173. /* Callback procs                                        */
  174. /*------------------------------------------------------------------------------------------ */
  175. typedef CALLBACK_API( OSStatus , HMControlContentProcPtr )(ControlRef inControl, Point inGlobalMouse, HMContentRequest inRequest, HMContentProvidedType *outContentProvided, HMHelpContentPtr ioHelpContent);
  176. typedef CALLBACK_API( OSStatus , HMWindowContentProcPtr )(WindowPtr inWindow, Point inGlobalMouse, HMContentRequest inRequest, HMContentProvidedType *outContentProvided, HMHelpContentPtr ioHelpContent);
  177. typedef CALLBACK_API( OSStatus , HMMenuTitleContentProcPtr )(MenuHandle inMenu, HMContentRequest inRequest, HMContentProvidedType *outContentProvided, HMHelpContentPtr ioHelpContent);
  178. typedef CALLBACK_API( OSStatus , HMMenuItemContentProcPtr )(const MenuTrackingData *inTrackingData, HMContentRequest inRequest, HMContentProvidedType *outContentProvided, HMHelpContentPtr ioHelpContent);
  179. typedef STACK_UPP_TYPE(HMControlContentProcPtr)                 HMControlContentUPP;
  180. typedef STACK_UPP_TYPE(HMWindowContentProcPtr)                     HMWindowContentUPP;
  181. typedef STACK_UPP_TYPE(HMMenuTitleContentProcPtr)                 HMMenuTitleContentUPP;
  182. typedef STACK_UPP_TYPE(HMMenuItemContentProcPtr)                 HMMenuItemContentUPP;
  183. #if OPAQUE_UPP_TYPES
  184.     EXTERN_API(HMControlContentUPP)
  185.     NewHMControlContentUPP           (HMControlContentProcPtr    userRoutine);
  186.  
  187.     EXTERN_API(HMWindowContentUPP)
  188.     NewHMWindowContentUPP           (HMWindowContentProcPtr    userRoutine);
  189.  
  190.     EXTERN_API(HMMenuTitleContentUPP)
  191.     NewHMMenuTitleContentUPP       (HMMenuTitleContentProcPtr userRoutine);
  192.  
  193.     EXTERN_API(HMMenuItemContentUPP)
  194.     NewHMMenuItemContentUPP           (HMMenuItemContentProcPtr userRoutine);
  195.  
  196.     EXTERN_API(void)
  197.     DisposeHMControlContentUPP       (HMControlContentUPP        userUPP);
  198.  
  199.     EXTERN_API(void)
  200.     DisposeHMWindowContentUPP       (HMWindowContentUPP        userUPP);
  201.  
  202.     EXTERN_API(void)
  203.     DisposeHMMenuTitleContentUPP    (HMMenuTitleContentUPP    userUPP);
  204.  
  205.     EXTERN_API(void)
  206.     DisposeHMMenuItemContentUPP       (HMMenuItemContentUPP    userUPP);
  207.  
  208.     EXTERN_API(OSStatus)
  209.     InvokeHMControlContentUPP       (ControlRef                inControl,
  210.                                     Point                    inGlobalMouse,
  211.                                     HMContentRequest        inRequest,
  212.                                     HMContentProvidedType *    outContentProvided,
  213.                                     HMHelpContentPtr        ioHelpContent,
  214.                                     HMControlContentUPP        userUPP);
  215.  
  216.     EXTERN_API(OSStatus)
  217.     InvokeHMWindowContentUPP       (WindowPtr                inWindow,
  218.                                     Point                    inGlobalMouse,
  219.                                     HMContentRequest        inRequest,
  220.                                     HMContentProvidedType *    outContentProvided,
  221.                                     HMHelpContentPtr        ioHelpContent,
  222.                                     HMWindowContentUPP        userUPP);
  223.  
  224.     EXTERN_API(OSStatus)
  225.     InvokeHMMenuTitleContentUPP       (MenuHandle                inMenu,
  226.                                     HMContentRequest        inRequest,
  227.                                     HMContentProvidedType *    outContentProvided,
  228.                                     HMHelpContentPtr        ioHelpContent,
  229.                                     HMMenuTitleContentUPP    userUPP);
  230.  
  231.     EXTERN_API(OSStatus)
  232.     InvokeHMMenuItemContentUPP       (const MenuTrackingData * inTrackingData,
  233.                                     HMContentRequest        inRequest,
  234.                                     HMContentProvidedType *    outContentProvided,
  235.                                     HMHelpContentPtr        ioHelpContent,
  236.                                     HMMenuItemContentUPP    userUPP);
  237.  
  238. #else
  239.     enum { uppHMControlContentProcInfo = 0x0000FBF0 };                 /* pascal 4_bytes Func(4_bytes, 4_bytes, 2_bytes, 4_bytes, 4_bytes) */
  240.     enum { uppHMWindowContentProcInfo = 0x0000FBF0 };                 /* pascal 4_bytes Func(4_bytes, 4_bytes, 2_bytes, 4_bytes, 4_bytes) */
  241.     enum { uppHMMenuTitleContentProcInfo = 0x00003EF0 };             /* pascal 4_bytes Func(4_bytes, 2_bytes, 4_bytes, 4_bytes) */
  242.     enum { uppHMMenuItemContentProcInfo = 0x00003EF0 };             /* pascal 4_bytes Func(4_bytes, 2_bytes, 4_bytes, 4_bytes) */
  243.     #define NewHMControlContentUPP(userRoutine)                     (HMControlContentUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppHMControlContentProcInfo, GetCurrentArchitecture())
  244.     #define NewHMWindowContentUPP(userRoutine)                         (HMWindowContentUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppHMWindowContentProcInfo, GetCurrentArchitecture())
  245.     #define NewHMMenuTitleContentUPP(userRoutine)                     (HMMenuTitleContentUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppHMMenuTitleContentProcInfo, GetCurrentArchitecture())
  246.     #define NewHMMenuItemContentUPP(userRoutine)                     (HMMenuItemContentUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppHMMenuItemContentProcInfo, GetCurrentArchitecture())
  247.     #define DisposeHMControlContentUPP(userUPP)                     DisposeRoutineDescriptor(userUPP)
  248.     #define DisposeHMWindowContentUPP(userUPP)                         DisposeRoutineDescriptor(userUPP)
  249.     #define DisposeHMMenuTitleContentUPP(userUPP)                     DisposeRoutineDescriptor(userUPP)
  250.     #define DisposeHMMenuItemContentUPP(userUPP)                     DisposeRoutineDescriptor(userUPP)
  251.     #define InvokeHMControlContentUPP(inControl, inGlobalMouse, inRequest, outContentProvided, ioHelpContent, userUPP)  (OSStatus)CALL_FIVE_PARAMETER_UPP((userUPP), uppHMControlContentProcInfo, (inControl), (inGlobalMouse), (inRequest), (outContentProvided), (ioHelpContent))
  252.     #define InvokeHMWindowContentUPP(inWindow, inGlobalMouse, inRequest, outContentProvided, ioHelpContent, userUPP)  (OSStatus)CALL_FIVE_PARAMETER_UPP((userUPP), uppHMWindowContentProcInfo, (inWindow), (inGlobalMouse), (inRequest), (outContentProvided), (ioHelpContent))
  253.     #define InvokeHMMenuTitleContentUPP(inMenu, inRequest, outContentProvided, ioHelpContent, userUPP)  (OSStatus)CALL_FOUR_PARAMETER_UPP((userUPP), uppHMMenuTitleContentProcInfo, (inMenu), (inRequest), (outContentProvided), (ioHelpContent))
  254.     #define InvokeHMMenuItemContentUPP(inTrackingData, inRequest, outContentProvided, ioHelpContent, userUPP)  (OSStatus)CALL_FOUR_PARAMETER_UPP((userUPP), uppHMMenuItemContentProcInfo, (inTrackingData), (inRequest), (outContentProvided), (ioHelpContent))
  255. #endif
  256. /* support for pre-Carbon UPP routines: NewXXXProc and CallXXXProc */
  257. #define NewHMControlContentProc(userRoutine)                     NewHMControlContentUPP(userRoutine)
  258. #define NewHMWindowContentProc(userRoutine)                     NewHMWindowContentUPP(userRoutine)
  259. #define NewHMMenuTitleContentProc(userRoutine)                     NewHMMenuTitleContentUPP(userRoutine)
  260. #define NewHMMenuItemContentProc(userRoutine)                     NewHMMenuItemContentUPP(userRoutine)
  261. #define CallHMControlContentProc(userRoutine, inControl, inGlobalMouse, inRequest, outContentProvided, ioHelpContent) InvokeHMControlContentUPP(inControl, inGlobalMouse, inRequest, outContentProvided, ioHelpContent, userRoutine)
  262. #define CallHMWindowContentProc(userRoutine, inWindow, inGlobalMouse, inRequest, outContentProvided, ioHelpContent) InvokeHMWindowContentUPP(inWindow, inGlobalMouse, inRequest, outContentProvided, ioHelpContent, userRoutine)
  263. #define CallHMMenuTitleContentProc(userRoutine, inMenu, inRequest, outContentProvided, ioHelpContent) InvokeHMMenuTitleContentUPP(inMenu, inRequest, outContentProvided, ioHelpContent, userRoutine)
  264. #define CallHMMenuItemContentProc(userRoutine, inTrackingData, inRequest, outContentProvided, ioHelpContent) InvokeHMMenuItemContentUPP(inTrackingData, inRequest, outContentProvided, ioHelpContent, userRoutine)
  265. /*------------------------------------------------------------------------------------------*/
  266. /* API                                                                                        */
  267. /*------------------------------------------------------------------------------------------*/
  268. /* Installing/Retrieving Content */
  269. EXTERN_API( OSStatus )
  270. HMSetControlHelpContent            (ControlRef             inControl,
  271.                                  const HMHelpContentRec * inContent);
  272.  
  273. EXTERN_API( OSStatus )
  274. HMGetControlHelpContent            (ControlRef             inControl,
  275.                                  HMHelpContentRec *        outContent);
  276.  
  277. EXTERN_API( OSStatus )
  278. HMSetWindowHelpContent            (WindowRef                 inWindow,
  279.                                  const HMHelpContentRec * inContent);
  280.  
  281. EXTERN_API( OSStatus )
  282. HMGetWindowHelpContent            (WindowRef                 inWindow,
  283.                                  HMHelpContentRec *        outContent);
  284.  
  285. EXTERN_API( OSStatus )
  286. HMSetMenuItemHelpContent        (MenuRef                 inMenu,
  287.                                  MenuItemIndex             inItem,
  288.                                  const HMHelpContentRec * inContent);
  289.  
  290. EXTERN_API( OSStatus )
  291. HMGetMenuItemHelpContent        (MenuRef                 inMenu,
  292.                                  MenuItemIndex             inItem,
  293.                                  HMHelpContentRec *        outContent);
  294.  
  295. /* Installing/Retrieving Content Callbacks */
  296. EXTERN_API( OSStatus )
  297. HMInstallControlContentCallback    (ControlRef             inControl,
  298.                                  HMControlContentUPP     inContentUPP);
  299.  
  300. EXTERN_API( OSStatus )
  301. HMInstallWindowContentCallback    (WindowRef                 inWindow,
  302.                                  HMWindowContentUPP     inContentUPP);
  303.  
  304. EXTERN_API( OSStatus )
  305. HMInstallMenuTitleContentCallback (MenuRef                 inMenu,
  306.                                  HMMenuTitleContentUPP     inContentUPP);
  307.  
  308. EXTERN_API( OSStatus )
  309. HMInstallMenuItemContentCallback (MenuRef                 inMenu,
  310.                                  HMMenuItemContentUPP     inContentUPP);
  311.  
  312.  
  313. EXTERN_API( OSStatus )
  314. HMGetControlContentCallback        (ControlRef             inControl,
  315.                                  HMControlContentUPP *    outContentUPP);
  316.  
  317. EXTERN_API( OSStatus )
  318. HMGetWindowContentCallback        (WindowRef                 inWindow,
  319.                                  HMWindowContentUPP *    outContentUPP);
  320.  
  321. EXTERN_API( OSStatus )
  322. HMGetMenuTitleContentCallback    (MenuRef                 inMenu,
  323.                                  HMMenuTitleContentUPP * outContentUPP);
  324.  
  325. EXTERN_API( OSStatus )
  326. HMGetMenuItemContentCallback    (MenuRef                 inMenu,
  327.                                  HMMenuItemContentUPP *    outContentUPP);
  328.  
  329. /* Enabling and Disabling Help Tags */
  330. EXTERN_API( Boolean )
  331. HMAreHelpTagsDisplayed            (void);
  332.  
  333. EXTERN_API( OSStatus )
  334. HMSetHelpTagsDisplayed            (Boolean                 inDisplayTags);
  335.  
  336. EXTERN_API( OSStatus )
  337. HMSetTagDelay                    (Duration                 inDelay);
  338.  
  339. EXTERN_API( OSStatus )
  340. HMGetTagDelay                    (Duration *                outDelay);
  341.  
  342. /* Compatibility */
  343. EXTERN_API( OSStatus )
  344. HMSetMenuHelpFromBalloonRsrc    (MenuRef                 inMenu,
  345.                                  SInt16                 inHmnuRsrcID);
  346.  
  347. EXTERN_API( OSStatus )
  348. HMSetDialogHelpFromBalloonRsrc    (DialogRef                 inDialog,
  349.                                  SInt16                 inHdlgRsrcID,
  350.                                  SInt16                 inItemStart);
  351.  
  352.  
  353. #if PRAGMA_STRUCT_ALIGN
  354.     #pragma options align=reset
  355. #elif PRAGMA_STRUCT_PACKPUSH
  356.     #pragma pack(pop)
  357. #elif PRAGMA_STRUCT_PACK
  358.     #pragma pack()
  359. #endif
  360.  
  361. #ifdef PRAGMA_IMPORT_OFF
  362. #pragma import off
  363. #elif PRAGMA_IMPORT
  364. #pragma import reset
  365. #endif
  366.  
  367. #ifdef __cplusplus
  368. }
  369. #endif
  370.  
  371. #endif /* __MACHELP__ */
  372.  
  373.